What a design system owes you
Two failed systems, one adopted one, and the difference that turned out to be documentation rather than code.
March 2026 — 6 min read
I have now watched three design systems land at the same company. The first two were better engineered than the third. The third is the one people use.
The failure was never technical
Both dead systems shipped clean, well-tested, well-typed components. Both were announced in a company meeting, documented thoroughly, and quietly routed around within a quarter. Engineers kept hand-rolling buttons, not out of spite but because reaching for the component meant accepting a decision they had not been part of and could not interrogate.
A component library is a set of arguments about how the product should behave. If you ship the conclusions and keep the arguments to yourself, you have shipped something people can only obey or ignore. Most choose ignore.
Say what it is not for
The change that moved adoption more than anything else was adding one section to every component page: when not to use this, and what to use instead.
It sounds like a small documentation flourish. What it actually does is prove that the component has a considered scope — that someone thought about the edges and is telling you where they are. A page that admits its own limits is a page you trust for the cases it does cover.
Refuse most requests
The strongest thing we did was set a rule for what earns a place: three teams have to have independently built it themselves before it becomes a component. Anything else is speculation dressed as service.
In a year that rule admitted six components and rejected somewhere over thirty. Nobody has missed the thirty. A system that grows to meet every request stops being a system and becomes a catalogue, and nobody reads a catalogue.
The number worth watching
Adoption rate is the metric everyone reports and it is close to meaningless on its own — you can get it to ninety per cent by making the alternative painful. The number I actually care about is how often someone reads a component page and then deliberately chooses something else.
If that number is zero, the docs are not being read, they are being complied with, and you will find out what people really thought the next time someone has room to rebuild.